Metadata-Version: 2.4
Name: legibilidad
Version: 1.0.0
Summary: Biblioteca Python para extracción de contenido legible de páginas web - Port de Mozilla Readability.js
Author: Port de Mozilla Readability
Maintainer: Port de Mozilla Readability
License: Apache-2.0
Project-URL: Homepage, https://github.com/usuario/legibilidad
Project-URL: Documentation, https://github.com/usuario/legibilidad#readme
Project-URL: Repository, https://github.com/usuario/legibilidad.git
Project-URL: Issues, https://github.com/usuario/legibilidad/issues
Keywords: readability,legibilidad,article,articulo,extraction,extraccion,reader,lector,firefox,mode,modo,lectura
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.28.0
Requires-Dist: lxml>=4.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: wxpython
Requires-Dist: wxPython>=4.2.0; extra == "wxpython"
Dynamic: license-file

# Legibilidad - Biblioteca Python para Extracción de Contenido

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

**Legibilidad** es un port completo de [Mozilla Readability.js](https://github.com/mozilla/readability) a Python 3.13, completamente traducido al español. Esta biblioteca permite extraer el contenido principal de artículos de páginas web, eliminando elementos no esenciales como publicidad, menús, barras laterales, etc.

Es la misma tecnología que utiliza Firefox en su [Modo de Lectura (F9)](https://support.mozilla.org/kb/firefox-reader-view-clutter-free-web-pages).

## 🚀 Características

- **Extracción inteligente de contenido**: Utiliza algoritmos de puntuación para identificar el contenido principal.
- **Metadatos completos**: Extrae título, autor, fecha de publicación, descripción, etc.
- **Soporte JSON-LD**: Extrae metadatos estructurados según Schema.org.
- **URLs absolutas**: Convierte automáticamente URLs relativas a absolutas.
- **Limpieza de HTML**: Elimina scripts, estilos y elementos no deseados.
- **Completamente en español**: Toda la API, documentación y mensajes están en español.
- **Compatible con Python 3.10+**: Desarrollado para Python moderno.

## 📦 Instalación

### Desde PyPI (cuando esté disponible):
```bash
pip install legibilidad
```

### Desde el código fuente:
```bash
git clone https://github.com/usuario/legibilidad.git
cd legibilidad
pip install -e .
```

### Con dependencias de desarrollo:
```bash
pip install -e ".[dev]"
```

### Con soporte para wxPython (para el ejemplo visual):
```bash
pip install -e ".[wxpython]"
```

## 🔧 Uso Básico

### Ejemplo simple

```python
from legibilidad import Legibilidad
from bs4 import BeautifulSoup
import requests

# Descargar una página web
url = "https://ejemplo.com/articulo"
respuesta = requests.get(url)
html = respuesta.text

# Crear el documento BeautifulSoup
documento = BeautifulSoup(html, 'html.parser')

# Analizar con Legibilidad
lector = Legibilidad(documento, url=url)
resultado = lector.analizar()

if resultado:
    print(f"Título: {resultado.titulo}")
    print(f"Autor: {resultado.autor}")
    print(f"Contenido: {resultado.contenido[:500]}...")
else:
    print("No se pudo extraer el contenido")
```

### Verificar si una página es probablemente legible

```python
from legibilidad import es_probablemente_legible
from bs4 import BeautifulSoup
import requests

url = "https://ejemplo.com/articulo"
respuesta = requests.get(url)
documento = BeautifulSoup(respuesta.text, 'html.parser')

if es_probablemente_legible(documento):
    print("Esta página probablemente tiene contenido legible")
else:
    print("Esta página probablemente no tiene contenido significativo")
```

### Opciones de configuración

```python
from legibilidad import Legibilidad, OpcionesLegibilidad
from bs4 import BeautifulSoup

html = "<html>...</html>"
documento = BeautifulSoup(html, 'html.parser')

# Configurar opciones
opciones = OpcionesLegibilidad(
    depurar=True,                    # Mostrar mensajes de depuración
    max_elementos_analizar=5000,     # Límite de elementos a analizar
    num_candidatos_top=5,            # Número de candidatos a considerar
    umbral_caracteres=500,           # Mínimo de caracteres requeridos
    mantener_clases=False,           # No preservar clases CSS
    clases_a_preservar=['codigo'],   # Excepto estas clases
    deshabilitar_json_ld=False,      # Analizar JSON-LD
)

lector = Legibilidad(documento, opciones=opciones)
resultado = lector.analizar()
```

## 📋 API de Referencia

### Clase `Legibilidad`

Constructor:
```python
Legibilidad(documento, opciones=None, url=None)
```

- `documento`: Objeto BeautifulSoup del documento HTML.
- `opciones`: Instancia de `OpcionesLegibilidad` (opcional).
- `url`: URL del documento para resolver URLs relativas (opcional).

Método principal:
```python
resultado = lector.analizar()
```

### Clase `ResultadoArticulo`

Propiedades del objeto retornado por `analizar()`:

| Propiedad | Tipo | Descripción |
|-----------|------|-------------|
| `titulo` | `str` | Título del artículo |
| `contenido` | `str` | HTML procesado del contenido |
| `contenido_texto` | `str` | Texto sin etiquetas HTML |
| `longitud` | `int` | Longitud en caracteres |
| `extracto` | `str` | Descripción o extracto breve |
| `autor` | `str` | Nombre del autor |
| `direccion` | `str` | Dirección del texto (ltr/rtl) |
| `nombre_sitio` | `str` | Nombre del sitio web |
| `idioma` | `str` | Código de idioma |
| `fecha_publicacion` | `str` | Fecha de publicación |

### Clase `OpcionesLegibilidad`

| Opción | Tipo | Defecto | Descripción |
|--------|------|---------|-------------|
| `depurar` | `bool` | `False` | Habilitar mensajes de depuración |
| `max_elementos_analizar` | `int` | `0` | Límite de elementos (0 = sin límite) |
| `num_candidatos_top` | `int` | `5` | Candidatos principales a considerar |
| `umbral_caracteres` | `int` | `500` | Mínimo de caracteres requeridos |
| `clases_a_preservar` | `list` | `[]` | Clases CSS a mantener |
| `mantener_clases` | `bool` | `False` | Preservar todas las clases |
| `deshabilitar_json_ld` | `bool` | `False` | No analizar JSON-LD |
| `modificador_densidad_enlaces` | `float` | `0.0` | Ajuste de densidad de enlaces |

### Función `es_probablemente_legible`

```python
es_probablemente_legible(documento, opciones=None)
```

- `documento`: Objeto BeautifulSoup.
- `opciones`: Diccionario con:
  - `longitud_contenido_minima` (int, defecto 140)
  - `puntuacion_minima` (int, defecto 20)
  - `verificador_visibilidad` (función)

Retorna `True` si el documento probablemente contiene contenido legible.

## 📁 Estructura del Proyecto

```
legibilidad/
├── __init__.py              # Exportaciones principales
├── legibilidad.py           # Clase principal Legibilidad
├── es_probablemente_legible.py  # Función de verificación rápida
├── expresiones_regulares.py # Patrones regex y constantes
├── analizador_dom.py        # Utilidades de manipulación DOM
└── procesamiento.py         # Funciones de procesamiento auxiliares

ejemplos/
├── ejemplo_basico.py        # Uso básico de la biblioteca
├── ejemplo_avanzado.py      # Opciones avanzadas
└── visor_wxpython.py        # Visor visual estilo Firefox

tests/
├── test_legibilidad.py      # Tests de la clase principal
├── test_es_legible.py       # Tests de verificación
└── test_procesamiento.py    # Tests de procesamiento
```

## 🖥️ Ejemplo Visual con wxPython

El proyecto incluye un visor visual similar al modo lectura de Firefox:

```bash
cd ejemplos
python visor_wxpython.py
```

Este visor permite:
- Ingresar una URL
- Extraer y mostrar el contenido legible
- Ver metadatos del artículo
- Copiar el contenido

## 🧪 Ejecutar Tests

```bash
# Instalar dependencias de desarrollo
pip install -e ".[dev]"

# Ejecutar tests
pytest

# Con cobertura
pytest --cov=legibilidad
```

## 🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu característica (`git checkout -b caracteristica/nueva`)
3. Commit tus cambios (`git commit -am 'Añadir nueva característica'`)
4. Push a la rama (`git push origin caracteristica/nueva`)
5. Abre un Pull Request

## 📄 Licencia

```
Copyright (c) 2010 Arc90 Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## 🙏 Agradecimientos

- [Mozilla](https://github.com/mozilla/readability) - Por el proyecto original Readability.js
- [Arc90](http://lab.arc90.com/experiments/readability/) - Por el proyecto original Readability

## 📞 Contacto

Para reportar bugs o sugerencias, por favor abre un [issue](https://github.com/usuario/legibilidad/issues).
